shellexpand 3.1.1

Shell-like expansions in strings
Documentation

shellexpand, a library for shell-like expansion in strings

Build Status crates.io docs

Documentation

shellexpand is a single dependency library which allows one to perform shell-like expansions in strings, that is, to expand variables like $A or ${B} into their values inside some context and to expand ~ in the beginning of a string into the home directory (again, inside some context).

This crate provides generic functions which accept arbitrary contexts as well as default, system-based functions which perform expansions using the system-wide context (represented by functions from std::env module and dirs crate).

Alternatives to this crate:

  • expanduser: Tilde substitution only. Supports ~user which this crate currently does not (although we hope to).
  • envsubst: Does not do offer tildeexpansion. Only supports certain concrete types (eg HashMap for variable map).
  • expand_str: Uses %..% syntax. Does not offer tilde expansion. Variable lookups can only be infallible.
  • tilde_expand: Only does tilde expansion, on bytes ([u8]).

Usage

Just add a dependency in your Cargo.toml:

[dependencies]
shellexpand = "3.0"

See the crate documentation (a link is present in the beginning of this readme) for more information and examples.

Cargo features

Functional features:

  • tilde (on by default): support for tilde expansion (home directory).
  • path (in full): support for operations on Paths. (MSRV: 1.51)

Metafeatures:

  • full: all reasonable (non-experimental, non-hazardous) functionality. (Currently equivalent to full-msrv-1.51.)
  • base-0 (on by default): basic functionality. You must enable this feature.
  • full-msrv-1.51: all reasonable functionality compatible with Rust 1.51. (currently: base-0, tilde, paths).
  • full-msrv-1.31: all reasonable functionality compatible with Rust 1.31. (currently: base-0, tilde).

At the time of writing there is no experimental or hazardous functionality; if we introduce any it will be feature gated and not enabled by default nor part of full*. Requiring base-0 allows us to split existing functionality into a new optional feature, without a semver break. We will try to avoid MSRV increases for existing functionality; increasing the MSRV for full will be minor version bump.

Changelog

Version 3.1.1 - 2025-04-14

Improved:

  • MSRV (1.31.0) declared in Cargo.toml.

Added:

  • Relaxed dependency on dirs to allow 6.x.

Version 3.1.0 - 2023-03-24

Added:

  • cargo features full-msrv-1.31 and full-msrv-1.51

Fixed:

  • Explicitly declared MSRV 1.51 for paths feature.
  • Fixed build (without paths feature) with MSRV (1.31)

Improved:

  • MSRV tested.
  • Update to dirs 5. (Allow use of dirs 4 too, since it's fine.)
  • Update Cargo.lock.exaple

Version 3.0.0 - 2022-12-01

Breaking changes:

  • tilde_with_context and full_with_context now expect home directories as str, not Path. If you want to deal in Path, use the path feature and module.
  • You must select at least one cargo feature. The base-0 feature is equivalent to the features available in shellexpand 2.x.

Significant changes:

  • Use Rust 2018, bumping MSRV to 1.31.0.
  • New path module, and corresponding cargo feature.

Version 2.1.2

Minor changes:

  • "Un-forked": now released as shellexpand on crates.io.
  • List alternatives to this crate.
  • Switch back to dirs from dirs-next.
  • Improve linking in docs and fix broken links and badges.
  • Apply some proposals from cargo fix.

Version 2.1.1

Version 2.1.0

  • Switched to dirs-next instead of the obsolete dirs as the underlying dependency used to resolve the home directory
  • Switched to GitHub Actions instead of Travis CI for building the project.

Version 2.0.0

  • Added support for default values in variable expansion (i.e. ${ANSWER:-42})
  • Breaking changes (minimum Rust version is now 1.30.0):
    • Using dyn for trait objects to fix deprecation warning
    • Switched to using source() instead of cause() in the Error implementation, and therefore added a 'static bound for the generic error parameter E

Version 1.1.1

  • Bump dirs dependency to 2.0.

Version 1.1.0

  • Changed use of deprecated std::env::home_dir to the dirs::home_dir function

Version 1.0.0

  • Fixed typos and minor incompletenesses in the documentation
  • Changed home_dir argument type for tilde expansion functions to FnOnce instead FnMut
  • Changed LookupError::name field name to var_name

Version 0.1.0

  • Initial release

License

This program is licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.